Text Descriptors

A text descriptor is a formatting command that describes the text that follows it. Exporting text with text descriptors allows you to edit text from a text track, including its formatting, in an external program, such as a text editor or word processor. When you import the edited text, the formatting you specified with the text descriptors is preserved. This provides an easy way to localize movies for different languages, correct spelling, change styles, or modify text behavior.

A text descriptor has the format{ descriptor } . For example, the text descriptor {bold} sets the text style in the current text sample and all subsequent text samples. Some text descriptors, such as {bold} , have no parameters. Other text descriptors have one or more parameters. For text descriptors with parameters, the descriptor is followed by a colon and its parameters, separated by commas. You can specify text descriptors using either uppercase or lowercase characters, with or without spaces separating the parameters:

For example, the text descriptor {font:New York} sets the text font in the current text sample and all subsequent text samples to the New York font. The New York font is applied to all text until a second {font:} text descriptor is issued.

A text stream that contains text descriptors and time stamps should always begin with the text descriptor {QTtext} , followed by any number of text descriptors in any order. If the text import component detects a typographical error inside a descriptor while importing a text file, it may generate partial results or an error message stating that the text file cannot be converted.

When text with text descriptors is imported into a track, the information represented by the descriptors is stored in a text display data structure (type TextDisplayData ). Text descriptors whose possible values are on and off are used to set flags in the displayFlags field of the text display data structure. Each sample in the text track has a corresponding text display data structure that contains the text attributes of the sample. For more information, see "Text Display Data Structure" .

Listing 1 shows a simple example of text that has been exported with text descriptors and time stamps. The text sample displays the text "I © QuickTime" (the "© "character is a "©" in the Macintosh Symbol font). The background color is black and the text color is white, except for the "©" character, which is drawn in red.

The {karaoke:} text descriptor allows you to highlight groups of characters in a text sample at specified times. For example, you might want to highlight the words in a song while playing the song's sound track. The parameters for the {karaoke:} text descriptor are specified as a set of tuples, separated by semicolons. The set of tuples is preceded by the total number of tuples:

{karaoke: count ; a1, a2, a3; b1, b2, b4; ... n1, n2, n3 } text sample

Each tuple is composed of a time value (which is greater than the one specified and less then the next time value), a starting offset into the text, and an ending offset into the text; at the specified time value, the text from the starting offset to the ending offset is highlighted.

The following example shows a {karaoke:} text descriptor followed by some text. The time scale of the movie was set to 600. The {karaoke:} text descriptor has 14 tuples. The second tuple indicates that, between 125/600 seconds and 250/600 seconds, the text from offset 0 to offset 4 ("Thun ") should be highlighted. The third tuple indicates that, after 250/600 seconds and before 350/600 seconds, the text from offset 4 to offset 7 ("der ") should be highlighted.

QuickTime 4 introduces the ability to include URL links directly in Text track samples. Links appear as underlined blue text in the same way that links are typically displayed in Web browsers. When the link text is clicked the URL is launched, opening a Web browser if necessary. The new {HREF:} and {endHREF} text descriptors both delimit the text serving as the link and indicate the URL that should be launched. The {HREF:} text descriptor's single parameter is the URL itself.

The link is performed using the "go to URL" wired action. At the application level, the controller action filter will see a mcActionLinkToURL action and can either consume the action or let it continue, sending it to the default Web browser.

Text dimensions

{height:}: Specifies the height of the text track in pixels. For example, the text descriptor {height:50} sets the text track height to 50 pixels. The text descriptor {height:0} sets the height to the best height for the text.
{width:}: Specifies the width of the text track in pixels. For example, the text descriptor {width:50} sets the text track width to 50 pixels. The text descriptor {width:0} sets the width to an appropriate default value or, if importing a movie, to the width of the movie.
{textBox:}: Specifies the coordinates of the text box. This text descriptor takes four parameters: top, left, bottom, and right. For example, if you specify {textBox:0, 0, 80, 320} (which is top, left, bottom, right), the text box originates at (0,0) and is 320 pixels wide and 80 pixels high.
{doNotAutoScale:}: Specifies whether to automatically scale the text if the track bounds increase. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . For example, the text descriptor {doNotAutoScale:off} enables auto-scaling. This corresponds to the dfDontAutoScale display flag.
{clipToTextBox:}: Specifies whether to clip to the text box. This is useful if the text overlays the video. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . This corresponds to the dfClipToTextBox display flag.
{shrinkTextBox:}: Specifies whether to recalculate the size of the text box specified by the {textBox:} text descriptor to fit the dimensions of the text. If so, the new rectangle is stored with the text data. This text descriptor takes one parameter. Possible values are on and off . The value of this text descriptor is used to set a flag in the displayFlags field of the text display data structure. This corresponds to the dfShrinkTextBoxToFit display flag.

Drawing text

{doNotDisplay:}: Specifies whether to display the sample. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . For example, the text descriptor {doNotDisplay:on} causes the sample to not be displayed. This corresponds to the dfDontDisplay display flag.
{justify:}: Specifies the alignment of the text in the text box. This text descriptor takes one parameter. Possible values are left , right , center , and default . For example, the text descriptor {justify:left} aligns text on the left. For more information on text alignment, see the chapter "TextEdit" in Inside Macintosh: Text .
{anti-alias:}: Specifies whether text should be displayed using anti-aliasing. Anti-aliasing smooths the edges of the text by blending the edge colors of the text and background. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . This corresponds to the dfAntiAlias display flag.
{textColor:}: Specifies the color of the text. This text descriptor takes three parameters: red, green, and blue color values. Each parameter should be between 0 and 65535. For example, the text descriptor {textColor:45000,0,0} sets the text color to a shade of red.
{backColor:}: Specifies the background color of the region specified by the {textBox:} text descriptor or the region specified by the {height:} and {width:} descriptors. This text descriptor takes three parameters: red, green, and blue color values. Each parameter should be between 0 and 65535. For example, the text descriptor {backColor:0,45000,0} sets the background color to a shade of green.
{hiliteColor:}: This display flag specifies the color to be used to highlight text. This text descriptor takes three parameters: red, green, and blue color values. Each parameter should be between 0 and 65535. For example, the text descriptor {hiliteColor:45000,0,0} sets the highlight color to a shade of red.
{inverseHilite:}: This display flag specifies whether to highlight text using reverse video instead of the highlight color. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . This corresponds to the dfInverseHilite display flag.
{keyedText:}: This display flag specifies whether text should be rendered over the background without drawing the background color. This technique is also known as masked text. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . This corresponds to the dfKeyedText display flag.
{hilite:}: Specifies characters to be highlighted in a text sample. This text descriptor takes two parameters, the first and last characters to highlight in the sample. For example, the text descriptor {hilite: 11, 14} highlights the word "text" in the text sample "This is a text track".
{textColorHilite:}: This display flag specifies whether text should be highlighted by changing the color of the text. This text descriptor takes one parameter. Possible values are on and off ; the default value is off .
{karaoke:}: Highlights groups of characters in the subsequent text sample at specified times. For example, you use this text descriptor to highlight the words in a song while playing the song's sound track. The parameters for this text descriptor are specified as a set of tuples of the form ( time value , starting offset , ending offset ), separated by semicolons. The set of tuples is preceded by the total number of tuples. For each tuple, at the specified time value, the text from the starting offset to the ending offset is highlighted.
{continuousKaraoke:}: This display flag specifies whether karaoke should ignore the starting offset and highlight all text from the beginning of the sample to the ending offset. Possible values are on and off ; the default value is off . If continuous karaoke is not enabled, karaoke highlights one offset range at a time. In order for this text descriptor to take effect, the karaoke text descriptor must be in effect. This corresponds to the dfContinuousKaraoke display flag.
{dropShadow:}: This display flag specifies whether the text sample supports drop shadows. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . This corresponds to the dfDropShadow display flag.
{dropShadowOffset:}: Specifies an offset for the drop shadow. This text descriptor takes two parameters, an offset to the right and an offset down. For example, the text descriptor {dropShadowOffset: 3, 4} offsets the drop shadow 3 pixels to the right and 4 pixels down. The default is {dropShadowOffset: 6, 6} . In order for this text descriptor to take effect, drop shadowing must be enabled.
{dropShadowTransparency:}: Specifies the intensity of the drop shadow. This text descriptor takes one parameter, a value between 0 and 255. The default value is 127. In order for this text descriptor to take effect, drop shadowing must be enabled.

Scrolling

{scrollIn:}: This display flag specifies whether text should be scrolled in until the last of the text is in view. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . If both {scrollIn:} and {scrollOut:} are set, the text is scrolled in and then scrolled out. If the {scrollDelay:} text descriptor is set, text is scrolled using the specified delay. This corresponds to the dfScrollIn display flag.
{scrollOut:}: This display flag specifies whether text should be scrolled out until the last of the text is in view. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . If both {scrollIn:} and {scrollOut:} are set, the text is scrolled in and then scrolled out. If the {scrollDelay:} text descriptor is set, text is scrolled using the specified delay. This corresponds to the dfScrollOut display flag.
{horizontalScroll:}: This display flag specifies whether to scroll a single line of text horizontally. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . If you do not specify this descriptor, the scrolling is vertical. The scrolling direction is determined by the {reverseScroll:} text descriptor. This corresponds to the dfHorizScroll display flag.
{reverseScroll:}: This display flag specifies whether to reverse the direction of scrolling. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . For vertical scrolling, the default direction is up. For horizontal scrolling, the default direction is left. For example, if you specify {reverseScroll:on} and {horizontalScroll:off} , the text is scrolled vertically down. This corresponds to the dfReverseScroll display flag.
{continuousScroll:}: This display flag specifies whether new samples should cause previous samples to scroll out. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . In order for this text descriptor to take effect, either {scrollIn:} or {scrollOut:} must be enabled. This corresponds to the dfContinuousScroll display flag.
{flowHorizontal:}: This display flag specifies whether text flows within the text box when it is scrolled horizontally. This text descriptor takes one parameter. Possible values are on and off ; the default value is off . For example, if you specify {flowHorizontal:off} , the text flows as if the text box had no right edge. In order for this text descriptor to take effect, horizontal scrolling must be enabled. This corresponds to the dfFlowHoriz display flag.
{scrollDelay:}: This display flag specifies a scroll delay for the sample. This text descriptor takes one parameter, the number of units of the delay in the text track's time scale. For example, if the time scale is 600, the text descriptor {scrollDelay: 600} causes subsequent text to be delayed one second. In order for this text descriptor to take effect, scrolling must be enabled.

Text Descriptors

General

Text styles

Text dimensions

Drawing text

Time stamps

Scrolling

URL links